<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
<html>
<head>
<title>Canopy HTTPd 0.1 Manual</title>

<link rel="stylesheet" type="text/css" href="/css/global.css">
</head>
<body>
<center>
<h1>Canopy HTTPd 0.1 Manual</h1>
<b>Jean-Fran&ccedil;ois Brousseau</b>
</center>
<br>
<br>
<p>
This is the official user's and developer's manual for version 0.1 of the
<a href="http://isdev11-mtl/canopy">Canopy HTTPd</a>
Web server.
If you are running a different version of the software, you should consult
the manual for that version.
</p>

<br>
<hr width="50%">
<h2 class="manual">Table of Contents</h2>

<ol>
<li><a href="#intro">Introduction</a></li>
<ol>
	<li><a href="#whatis">What is Canopy HTTPd?</a></li>
	<li><a href="#why">Why should I use Canopy HTTPd?</a></li>
	<li><a href="#about">About This Document</a></li>
	<ol>
		<li><a href="#scope">Document Scope</a></li>
		<li><a href="#conventions">Typographical Conventions</a></li>
		<li><a href="#license">License</a></li>
		<li><a href="#history">Revision History</a></li>
	</ol>
</ol>
<li><a href="#install">Building and Installing Canopy HTTPd</a></li>
<ol>
	<li><a href="#sysreq">System Requirements</a></li>
	<ol>
		<li><a href="#osreq">Platform Requirements</a></li>
		<li><a href="#compreq">Compilation and Installation</a></li>
		<li><a href="#rtreq">Runtime Environment</a></li>
		<li><a href="#platform">Platform-Specific Issues</a></li>
	</ol>
	<li><a href="#getting">Getting a Distribution</a></li>
	<ol>
		<li><a href="#bindist">Binary Distribution</a></li>
		<li><a href="#srcdist">Source Distribution</a></li>
	</ol>
	<li><a href="#compilation">Compilation Instructions</a></li>
	<li><a href="#installation">Installation Instructions</a></li>
</ol>
<li><a href="#using">Configuring and Running Canopy HTTPd</a></li>
<ol>
	<li><a href="#cli">Command-Line Usage</a></li>
	<li><a href="#conffile">The Configuration File</a></li>
	<li><a href="#logging">Message Logging</a></li>
	<li><a href="#running">Running Canopy HTTPd</a></li>
</ol>

<li><a href="#tasks">Design and Implementation</a></li>
<ol>
</ol>
</ol>

<ol class="appendix">
<li><a href="#glossary">Glossary</a></li>
<li><a href="#examples">Examples</a></li>
</ol>

<br>
<hr width="50%">

<h2 class="manual"><a name="intro">Chapter 1 - Introduction</a></h2>

<p>
Welcome to the official HTML manual for the Canopy HTTPd server.
This manual is aimed at users, system administrators, software developers
or anyone interested in learning how Canopy HTTPd works.
It covers everything, from installation and configuration to extending the
system by writing modules.
</p>
<p>
If this is the first time you read about Canopy HTTPd, it is strongly suggested
that you read at least the first chapter, to get a good idea of what it does
and what it doesn't do.
</p>

<h3><a name="whatis">1.1 - What is Canopy HTTPd?</a></h3>

<p>
</p>

<h3><a name="why">1.2 - Why should I use Canopy HTTPd?</a></h3>
<p>
</p>

<h3><a name="about">1.3 - About This Document</a></h3>

<h4><a name="scope">1.3.1 - Document Scope</a></h4>

<p>
This document is limited in scope to the installation, configuration,
usage and implementation of the Canopy HTTPd server.  It does not cover
other tools that might be required for any of the steps mentioned above.
</p>
<p>
Portions of this document assume that the reader has at least basic
knowledge of UNIX-derived operating systems, the Java programming
language, and the Apache Software Foundation's Ant build tool.
</p>

<h4><a name="conventions">1.3.2 - Typographical Conventions</a></h4>

<p>
This document makes use of several typographical conventions throughout the
text that are meant to make it easier to read and understand.
These conventions are described below.
</p>

<h5><a name="">1.3.2.x - Directory and File Paths</a></h5>

<p>
Whenever a reference to a filename or filesystem path is made in the text,
that name or path will appear in a <tt>fixed-width font</tt>.

<h5><a name="">1.3.2.x - Source Code</a></h5>
<p>
References to methods, routines, classes and other source code constructs
directly in the text are printed in a <tt>fixed-width font</tt>.
</p>

<p>
When several consecutive lines of source code are listed, they appear in
a centered box with a thin black border and a light gray background, like in
the following example:
</p>

<pre class="source">
<font color="#0000ff">/*
 * When applicable, colors are used to highlight specific constructs
 * in the source code.  For example, in Java source code, comments
 * appear in blue, language keywords are in bold.
 */</font>
<b>struct</b> mystruct {
	<b>int</b>      myvar;
	<b>char</b>    *foo;
}
</pre>


<h5><a name="">1.3.2.x - Shell Commands</a></h5>
<p>
In some portions of this manual, the document specifies commands that can be
executed from a command shell.  In such cases, the shell output and the
commands to execute are shown in a centered box with a black background.  The
shell prompt and program output are shown in white and the commands to
execute are shown in green, such as in this example:
</p>

<pre class="shell">
shell> <font color="#00ff00">echo "This is a command"</font>
This is a command
shell>
</pre>

<h5><a name="">1.3.2.x - Important Notes</a></h5>
<p>
Whenever the author wants to emphasize on a particular point, a special note
box will be inserted in the text.  A note box has an exclamation mark and the
title <b>Note</b>.
</p>

<center>
<table class="note" border="0">
<tr><th>
	<img src="images/exclamation_sign.png">&nbsp;&nbsp;Note
</th></tr>
<tr><td>
A note like this one is used whenever the author wants to emphasize
a portion of the text.
</td></tr>
</table>
</center>
<br>
<br>

<h4><a name="license">1.3.2 - License</a></h4>
<p>
</p>

<p>
</p>

<h4><a name="history">1.3.4 - Revision History</a></h4>

<table cellpadding="10" cellspacing="1">
<tr>
	<th>Revision</th>
	<th>Date</th>
	<th>Author</th>
	<th>Changes</th>
</tr>
<tr>
	<td>First draft</td>
	<td>August, 7</td>
	<td>Jean-Fran&ccedil;ois Brousseau</td>
	<td>First version of this document</td>
</table>

<br>
<br>
<hr width="50%">
<h2 class="manual"><a name="install">Chapter 2 - Building and Installing Canopy HTTPd</a></h2>
<p>
This chapter covers the steps required to get an Canopy HTTPd distribution and
install it.  It covers all the details related to the installation, such
as system requirements, software prerequisites, standard directory hierarchy.
</p>

<h3><a name="sysreq">2.1 - System Requirements</a></h3>
<p>
Before proceeding to the installation, you will need to verify that
minimum hardware requirements are met and prerequisite software components
are properly installed and configured.
</p>

<h4><a name="osreq">2.1.1 - Platform Requirements</a></h4>
<p>
</p>

<h4><a name="compreq">2.1.2 - Compilation and Installation</a></h4>

<p>
</p>

<h4><a name="rtreq">2.1.3 - Runtime Environment</a></h4>
<p>
</p>

<h4><a name="platform">2.1.4 - Platform-Specific Issues</a></h4>

<p>
Completely untested on Windows platforms.
</p>

<h3><a name="getting">2.2 - Getting a Distribution</a></h3>

<p>
If you do not already have an Canopy HTTPd distribution file, you can get one
from the project's official Web download page, which can be found
<a href="http://code.google.com/p/canopy-httpd/">
here</a>.
You should get the latest stable distribution in order to have as many features
and bugfixes as possible.
</p>

<center>
<table class="note">
<tr><th align="left">
	<img src="images/exclamation_sign.png">&nbsp;&nbsp;Note
</th></tr>
<tr><td>
Make sure that you read the proper version of this manual according to the
Canopy HTTPd release that you have chosen to install.  Installation instructions
can change between releases.
</td></tr>
</table>
</center>
<br>

<h4><a name="bindist">2.2.1 - Binary Distribution</a></h4>

<p>
A binary distribution is an archive file that
contains a compiled version of the software and an installation script or a
simple set of procedures.
</p>

<h4><a name="srcdist">2.2.2 - Source Distribution</a></h4>

<p>
A source distribution is an archive file that contains a complete snapshot of
the project's source code repository at a given time.  With a source
distribution, you have access to the project's source code and you can build
binary distributions or do a direct installation.  Source distributions are
normally useful to people who want to understand or modify the tool.
</p>

<h3><a name="compilation">2.3 - Compilation Instructions</a></h3>
<p>
In the following example, we are going to use the source distribution file
for Canopy HTTPd 0.1, which is named <i>canopy-0.1-src.tar.gz</i>
</p>

<pre class="shell">
shell> <font color="#00ff00">cd /tmp</font>
shell> <font color="#00ff00">ls</font>
canopy-0.1-src.tar.gz
shell> <font color="#00ff00">tar -xzf canopy-0.1-src.tar.gz</font>
shell> <font color="#00ff00">ls</font>
canopy-0.1-src       canopy-0.1-src.tar.gz
shell> <font color="#00ff00">cd canopy-0.1-src</font>
shell> <font color="#00ff00">make && make install</font>
</pre>

<h3><a name="installation">2.3 - Installation Instructions</a></h3>
<p>
To install Canopy HTTPd, you will need either a compiled source distribution
or a binary distribution.
</p>

<h4><a name="">2.3.1 - Installing From Source</a></h4>
<p>
If you have a source distribution and compilation
</p>

<pre class="shell">
shell> <font color="#00ff00">make install</font>
</pre>

<h4><a name="">2.3.1 - Installing From a Binary Distribution</a></h4>
<p>
</p>


<pre class="shell">
shell> <font color="#00ff00">./install.sh</font>
</pre>

<br>
<hr width="50%">
<h2 class="manual"><a name="using">Chapter 3 - Configuring and Running Canopy HTTPd</a></h2>
<p>
This chapter will focus on the procedures required to properly configure and
run the Canopy HTTPd server.
</p>

<h3><a name="cli">3.1 - Command-Line Usage</a></h3>

<pre class="shell">
Usage: canopy [-c config]

	-c <config>	Use <config> as the main configuration file
</pre>

<h3><a name="conffile">3.2 - The Canopy HTTPd Configuration File</a></h3>
<p>
Upon startup, Canopy HTTPd always reads its main configuration file, which it
expects to find in <i>/usr/local/etc/canopy.conf</i> by
default.  This value can be overriden through the use of the <tt>-c</tt>
command-line option (see <a href="cli">3.1 - Command-Line Usage</a> for
more details).
</p>


<h3><a name="logging">3.3 - Message Logging</a></h3>
<p>
</p>

<h3><a name="running">3.4 - Running Canopy HTTPd</a></h3>

<h4><a name="">3.4.3 - Configuring Automatic Startup</a></h4>
<p>
</p>

<h3><a name="">3.x - Runtime Security Features</a></h3>
<p>
There are several features built into Canopy HTTPd that can be used to make
the deployment more secure.
</p>

<h4><a name="">3.x.1 - Privilege Separation</a></h3>
<p>
</p>

<h4><a name="">3.x.2 - Changing the Root Directory</a></h3>
<p>
</p>


<br>
<hr width="50%">
<h2 class="manual"><a name="extending">4 - Design and Implementation</a></h2>

<p>
This chapter explains the internals of the Canopy HTTPd server
</p>



<br>
<hr width="50%">
<h2 class="manual"><a name="glossary">Appendix A - Glossary</a></h2>

<dl>
<dt><b>API</b></dt>
<dd>
The acronym for Application Programming Interface.
The specification of how a programmer writing an application accesses
the behavior and state of classes and objects. 
</dd>

<dt><b>Reentrant</b></dt>
<dd>
A characteristic of a software program, function or routine that can be called
recursively and simultaneously by multiple processes without impact on any
of the instances.
</dd>
</dl>

<br>
<hr width="50%">
<h2 class="manual"><a name="examples">Appendix B - Examples</a></h2>
<br>
<hr>
</body>
</html>
